Subject: Comments to Jeff's proposal

From: [email-masked]
Date: Thu, 17 Feb 94 15:20:17 +0100

Here are our comments to Jeff's proposal:

>  ----------------------- Requirements ------------------------------------
> Introduction
> 
> The requirement this paper addresses is the encoding and decoding of data for
> transmission on the a network.  Traditionally the encoding and decoding of
> data has been a problem the application's programmer dealt with.  The advent 
> of the LU 6.2 protocol saw the first mention that the encoding and decoding of
> network data stream can be separated from the application program and given
> to the underlying system.. LU 6.2 described a user written routine that node 
> services could call to perform either encoding or decoding of a network data 
> stream.  This method allowed all the programs that processed a specific
> transaction type to use a common encode/decode routine.  These routines were 
> envisioned to allow not only data conversion but also preprocessing of the
> data, for example to rearrange the fields to suit a local record format.
> Unfortunately, the concept as specified in the LU 6.2 protocol was not
> implemented.  What was implemented is a mechanism which chops an
> application's data stream into regular size chunks for transmission and
> reconstructs the data record on the receiver's side.  What has become known as
> mapped conversations in the LU 6.2 environment is really a simple buffering
> mechanism.  A simple buffering mechanism is all that is really needed if the 
> program only deals in one or two record types and moves those between
> homogenous machines.
> 
> OSI TP has very different requirements.  The experience I have had writing
> OSI programs indicates ASN.1 encoding and decoding of network data
> streams can be complex and occupy significant portions of the application
> program's code.  This is not an indictment of ASN.1 encoding.  
> Architecturally OSI TP addressed this by removing the encoding and decoding
> from the application program and placing it in the U-ASE which is located in
> the OSI CRM.  This approach provides three advantages:
> 
> 1.It allows the applications programmer to focus on the problem to be
> solved rather than the mechanical encoding and decoding of data.
> 
> 2.A small group of one or two people can support an organization in the
> construction and maintenance of U-ASEs.  These people can develop
> the required skills to create and maintain U-ASEs that only repetitive
> usage provides.
> 
> 3.A single U-ASE can be used by many programs and therefore realizes
> all the benefits of code-reuse.
> 
> The key is to balance the needs of programs with complex encoding
> requirements against those which have very simple needs, the next section
> addresses this.
> 
> Encoding/Decoding Requirements:
> The solution must support the transfer of both application program encoded
> network data streams and CRM encoded (ASN.1 or other encoding methods)
> network data streams.
> 
> The first requirement, application program encoding/decoding, is resolved by 
> using the current LU 6.2 mapped conversation mechanism, and the OSI TP
> Unstructured Data Transfer U-ASE (UDT).  The application program sends an
> internal data structure, for example a COBOL 01 level structure or C language
> struct, as the network data stream to the receiving program.  This method
> works well when the number of programs are small and the computing
> platforms are homogeneous, for example they both support OCTAL or EBDIC
> character sets.  If the cooperating systems support different character sets 
> some form of encoding is required.  Less obvious, is the problem that arise
> when too many systems are involved.  Essentially, various systems want
> changes in a network data stream to facilitate what they are doing.  These
> changes require all other systems to also change.  With a small number of
> closely related systems this is not a problem.  As the number of systems
> increase this becomes a major problem because systems that have no use for a 
> change must implement it, and, worse, simultaneously with all the other
> systems.  The coordination required for these changes becomes excessive and
> the wasted man hours required to implement the changes for nonbnefitting
> system are enormous.  I have a situation at Boeing which illustrates this exact
> problem, our temporary solution is to put a shim layer that performs a
> mapping function between CPIC and the communications stack .  This shim
> will go away when CPIC supports external encoding/decoding routines for
> mapped conversations.
> 
> The second requirement, CRM encoded/decoded network data streams, is
> satisfied by supporting the OSI TP CRM's U-ASE, or LU 6.2 Maps (see foot note).
> This requires the use of external routines to encode/decode network data
> streams. 
> 
> This method is needed when:
> 
> 1.The network data stream must be encoded/decode in a manner more
> complex than simply sending a program's internal data structure.
> 
> 2.There is a need to have variations in a network data stream.
> 
> How an implementation supports external encode/decode routines is vendor
> specific.  The routines could, for example, be in dynamic link libraries or 
> link edited into the load module.
> 
> (foot note)  Maps are non-SNA-defined transformation tables or procedures 
> that can be defined by the installation at both the source and target LUs.
> Maps can specify, for example, how fields of a mapped-conversation are related
> to TP variables (data record) referred to in protocol-boundary verbs. Mapping
> is performed by a PS.MC component called the mapper.
> SNA Format and Protocol Reference Manual: Architecture Logic for LU Type 6.2,
> SC30-3269,  page 2-39
> 
>  -----------------------------  Change pages -------------------------
> 
> 
> Page 10: replace mapped conversation paragraph with
> *Mapped conversations allow programs to exchange arbitrary data records
> in data formats agreed upon by the application programmers.  If no
> map_name is set, via a SET_MAP_NAME call, the data record is treated
> as it was in CPIC 1.0.  If a map_name is supplied the sender and receiver
> will use external routines to encode/decode the data record as well as
> perform any other agreeded upon processing.  How these routines are
> written, stored, and attached to user programs is implementation specific,
> and not specified by this specification.
> 
> Page 17: add to starter set calls SET_MAP_NAME and EXTRACT
> _MAP_NAME.  These should be added here instead of under advanced
> functions because the default conversation type is mapped.

(remark 1) ===>
We do not agree. Set_Map_Name and Extract_Map_Name should not be
part of the starter set. Also they should not be part of the
mandatory conformance class. We should define a new conformance
class for these 2 calls.

> 
> Page 23: add to Characteristics and their default values table - map_name.  
> For all four cases indicate "Not set".
> 
> Page 33: add to last paragraph of Data Conversion after last sentence.  
> Refer mapped conversation calls SET_MAP_NAME on page xyz and
> EXTRACT_MAP_NAME on page xyz for more advanced data conversion capabilities.
> 
> Page 87: add to call reference table.
>     Set_Map_Name  CMSTMP  Used by an application program to tell CPI-C
>             what encoding routine to use.
>     Extract_Map_Name  CMEXMP Used by the local system to inform the
>            application program what data record it received.

(remark 2) ===>
Our change request: Take the names CMEMPN and CMSMPN instead of
CMEXMP and CMSTMP. In all the other CPI-C calls E is the abbreviation of
Extract and S the abbreviation of Set.

> 
> Page 110: add to related information.  "Extract_Map_Name (CMEXMP) on
> page xx provides information on data conversion using mapped
> conversations.
> 
> Page 112: add to related information.  "Set_Map_Name (CMSTMP) on page
> xx provides information on data conversion using mapped conversations.
> 
> Page 184: add to related information.  "Extract_Map_Name (CMEXMP) on
> page xx provides information on data conversion using mapped
> conversations.
> 
> Page 184: add to Usage Notes.
> 4. If a mapped conversation is using the map_name characteristic, on a receive
> delallocate the program will perform two receives.  The first receive will
> return CM_OK and CM_DATA_COMPLETE, the program can then issue
> an Extract_Map_Name to learn what data record was sent.  The second
> receive will return a CM_OK DELLAOCATE, there will be no user data
> return and the program can terminate.
> 
> Page 198: add to related information.  "Set_Map_Name (CMSTMP) on page
> xx provides information on data conversion using mapped conversations.
> 
> Page 198: add to Usage Notes.
> 10. The map_name characteristic is persistant and only needs to be set when
> the map_name being used differs from the previous name.  For example, a
> program which uses only one map_name need only set it once.
> 
> Page 336: State tables.  Add to Receive(I) & (W) event {ok} {dr no} a note.
> Note: In the case of mapped conversation receiving a Receive_and_Deallocate
> will behave in one of two ways.  Mapped conversations which do not use
> the map_name characteristic the receiver will receive the data record and a
> DEALLOCATE indication.  Mapped conversations which use the
> map_name characteristics will execute two receives.  The first will receive
> the decoded data record and the CM_OK DATA_COMPLETE
> indications.  The second receive will receive a DEALLOCATE indication,
> and no user data will be returned.  This sequence allows the program to
> issue an Extract_Map_Name call after the first receive.

(remark 3) ===>
We do not agree. We don't need a note to the state table. The existing state
table does not describe that an incoming data record together with a
deallocate indication is indicated as [dn] {dr,no}. The existing CPI-C
document also allows that the implementation makes 2 indications of
this event: [ok] {dr,no} and [dn] {*,no}.
Therefore we need no change to the state table.
Instead of this we could add an implementor's note to the Receive call.

> 
> Proposed new calls, as presented in the December 
> meeting.----------------------- -
> 
> 
> Set_Map_Name (CMSTMP)
> 
> Set_Map_Name (CMSTMP)
> A program uses the Set_Map_Name (CMSTMP) call to communicate to the local
> system what data record the application program is going to send.  The remote 
> partner program uses the Extract_Map_Name to retrieve the name of the data
> record it was sent.  This service must be used if the program sends multiple
> data record types.  It may be ignored if the mapped conversation only supports
> one data record type. 

(remark 4) ===>
How does the CRM know if a data record shall be encoded using UDT or some 
other syntax ? In other words, what is the default presentation context if
no Map_Name is specified ?

>                       Depending on the underlying CRM the data record may be
> further processed when it is given to the local system at SEND_DATA time, see
> usage notes.
> 
> Format
> 
> CALL CMSTMP    (conversation_ID,
>                map_name,
>                return_code)
> Parameters
> 
> Conversation_ID (input)
> Specifies the variable containing the conversation identifier
> assigned to the conversation.
> 
> map_name (input)
> Specifies the mapping function to be used to encode the
> data record.  This is a positive integer value.

(remark 5) ===>
We do not agree. It was an agreement at the last CIW meeting that
map names should be in character format. So we need two parameters
- map_name        (char *) 
- map_name_length (int *)

> 
> return_code (output)
> Specifies the result of call execution.  The return_code
> variable can have one of the following values:
> 
> *    CM_OK
> *    CM_PROGRAM_STATE_CHECK
> 	  This value indicates that the sym_dest_name specifies an unrecognized
> 	  value.

(remark 6) ===> 
1) replace sym_dest_name by map_name.
2) this return code usually describes some state table violation and is 
   inadequate in this situation. Instead CM_PARAMETER_ERROR should be used.

> *    CM_OPERATION_NOT_ACCEPTED
> 	  This value indicates the map_name value was not valid map.

(remark 7) ===> 
1) this return code usually describes an operation-incomplete situation and is 
   inadequate in this situation. Instead CM_PARAMETER_ERROR should be used.
2) to distinguish between an unrecognized value of map_name (e.g. not 
   configured in the local implementation) and an invalid map_name (e.g. the
   corresponding presentation context was rejected when the defined context set
   was negotiated on association setup time) different secondary information
   codes associated with CM_PARAMETER_ERROR should be used.
3) CM_OPERATION_NOT_ACCEPTED must be a valid return code, but with a
   different meaning.

> *    CM_PRODUCT_SPECIFIC_ERROR
> 
> State Changes
> This call does not cause a state change.  If more than one data record type 
> is supported this service must be invoked prior to a SEND_DATA.
> 
> Usage Notes
> Programs which only have one map name, e.g., have only one data record type 
> can ignore this service.  The MAP_NAME for a mapped conversation has a default
> value of 1.
 
(remark 8) ===>
1) see remark 4.
2) The default value should be a null string (i.e. map_name_length = 0).

> 
> Related Information
> LU 6.2 CRM's use this service to set the MAP_NAME parameter on the
> MC_SEND_DATA service to "YES (value of the Set_Map MAP_NAME parameter)".
> 
> OSI TP CRM's passes the service's MAP_NAME parameter to the U-ASE which:
> 
>      1.Encodes the data record using the proper abstract syntax. Note, there 
> 	  is no need to transmit the map_name because it is carried as the tag
> 	  for the specific ASN.1 construct used to encode the data.
>      2.Performs any other user defined action on the data record.  An 
> 	  example of this would be a security transformation on the data
> 	  record.
> 
> 
> Extract_Map_Name (CMEXMP)
> 
> Extract_Map_Name (CMEXMP)
> 
> A program uses the Extract_Map_Name (CMEXMP) call to communicate to the local
> system what data record is to be sent.  

(remark 9) ===>
The last sentence should be ommited.

>                                         The receiving program uses the
> Extract_Map_Name to retrieve the name of the data record it was sent.
> Depending on the underlying CRM the data record may be further processed 
> when it is given to the local system at SEND_DATA time, see usage notes.
> 
> Format
> CALL CMSTMP    (conversation_ID,
>                map_name,
>                return_code)

(remark 10) ===>
Change CMSTMP to CMEMPN.

> 
> Parameters
> 
> Conversation_ID (input)
> Specifies the variable containing the conversation identifier
> assigned to the conversation.
> 
> map_name (output)
> Specifies the mapping function used to encode the data
> record.  This is a positive integer value.

(remark 11) ===>
1) see remark 5
2) it should be "decode" rather than "encode"

> 
> return_code (output)
> 
> Specifies the result of call execution.  The return_code
> variable can have one of the following values:
> *    CM_OK
> *    CM_PROGRAM_STATE_CHECK
>      This value indicates that the sym_dest_name specifies
>           an unrecognized value.

(remark 12) ===>
see remark 6

> *    CM_OPERATION_NOT_ACCEPTED
>      This value indicates the map_name value was not valid
>           map.

(remark 13) ===>
see remark 7

> *    CM_PRODUCT_SPECIFIC_ERROR
> 
> State Changes
> 
> This call does not cause a state change.  If more than one data record type 
> is supported this service must be invoked after a RECEIVE.
> 
> Usage Notes
> Programs which only have one map name, e.g., have only one data record type 
> can ignore this service.  The MAP_NAME for a mapped conversation has a default
> value of 1.
> 
> Related Information
> LU 6.2 CRM MC_RECEIVE_XXX services will have the MAP_NAME parameter set to
> the incoming map_name.
> 
> OSI TP CRM U-ASEs will know what the map name is from the ASN.1 tag of the
> incoming user data record.  The Extract_Map_Name service is used to find out 
> what data record was sent so that it can be properly processed.